Description

This PR adds custom document metadata support across backend, API and WebUI. Users can now attach arbitrary key-value metadata to documents during insertion, update them and retrieve documents with metadata during queries.

Related Issues

None

Changes Made

Backend (lightrag/)

• base.py: Added include_metadata field to QueryParam class
• lightrag.py:
  • Updated ainsert() to accept and process metadata parameter
  • Updated aquery() to support metadata via QueryParam
• operate.py: Integrated metadata into document chunking and storage
• utils.py: Added metadata serialization/deserialization utilities and validation helpers

API (lightrag/api/routers/)

• document_routes.py:
  • Updated /documents/text and /documents/file endpoints to accept metadata
  • Added /documents/{document_id}/metadata endpoint for updating metadata via PATCH method
• query_routes.py:
  • Added metadata support to /query endpoint via include_metadata flag
  • Updated query response to include document metadata when requested

WebUI (lightrag_webui/)

• api/lightrag.ts: Added TypeScript API client methods for metadata operations
• components/documents/MetadataEditorDialog.tsx: New component for editing document metadata
• features/DocumentManager.tsx: Integrated metadata editor dialog into document management UI
• locales/en.json: Added strings for metadata features

Checklist

• Changes tested locally (see notes)
• Code reviewed
• Documentation updated (see notes)
• Unit tests added (if applicable)

Additional Notes

Implementation:

• Custom metadata storage leverages the existing metadata logic used for system fields (is_duplicate, original_doc_id, original_track_id, processing_start_time, processing_end_time)
• System-reserved fields are protected: viewable but not editable through WebUI (indicated by lock icon) or API (returns error)
• Metadata handling logic has been updated to merge custom fields provided during document insertion with system fields added through document processing pipeline

Testing:

• Insertion with metadata (for /documents/text endpoint) and metadata update operations have been tested
• Querying remains UNTESTED due to need of embedding model and LLM set up

Documentation:

• API documentation has been updated within the WebUI interface
• Additional markdown documentation for the metadata feature may be added later